home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 February: Tool Chest / Dev.CD Feb 99 TC.toast / What's New? / Development Kits / Mac OS USB v1.1f3 DDK / Mac OS USB DDK Readme < prev    next >
Encoding:
Text File  |  1999-01-06  |  16.6 KB  |  449 lines  |  [ttro/ttxt]
  1.  ***
  2.  ***       Universal Serial Bus(tm) (USB) for the Mac OS
  3.  ***    Mac OS USB 1.1f3 DDK Developer Release Notes
  4.  ***    Copyright 1998 Apple Computer, Inc.
  5.  ***
  6.  
  7.  
  8.  Table of Contents:
  9. -------------------------------------------------------------
  10.  Changes from USB v1.0 -> v1.1
  11.  USB Fundamentals
  12.  Keeping up to date on Mac OS USB
  13.  Getting started with Mac OS USB
  14.  Installing the Mac OS USB Software
  15.  Using the Mac OS USB DDK under MPW
  16.  Using the Mac OS USB DDK with MetroWerks CodeWarrior
  17.  Installing the Mac OS USB DDK for CodeWarrior for the First Time  
  18.  Updating a Previously Installed Mac OS USB DDK for CodeWarrior
  19.  Using the CodeWarrior Project Files
  20.  Installing the Mac OS USB Components onto your Target System
  21.  Description of Installed Files
  22.  Known Problems and Issues
  23.  Contact Information
  24. -------------------------------------------------------------
  25.  
  26. Changes from USB v1.0 -> v1.1
  27. -----------------------------
  28.  
  29. Refer to the document "Mac OS USB v1.1 Readme" for a description
  30. of the changes between the v1.0 and v1.1 DDK.
  31.  
  32. EXTREMELY IMPORTANT - CAREFULLY read the instructions below on how to
  33. install this release of software. The installation of this software
  34. is different from all previous releases.
  35.  
  36. This software release of Mac OS USB is for development purposes only.
  37. Rather than make this release accessible from a priviledged site,
  38. instead, a modification to the software is required which developers
  39. should be familiar with.
  40.  
  41. USB Fundamentals
  42. ----------------
  43.  
  44. For the coming generation of Power Macintosh systems, USB is the 
  45. primary interface for connections to low to medium speed peripheral
  46. devices. There are numerous advantages for adopting the USB standard on
  47. Macintosh, and they are discussed in the "Mac OS USB DDK API Reference
  48. Guide". On the future Macintosh systems there will be no ADB, 
  49. Serial Port, or SCSI connections. USB will be the primary port 
  50. for connecting peripheral devices to the Macintosh. 
  51.  
  52. The DDK provides the tools, interfaces, system files, and module 
  53. examples for you to start development of USB products
  54. for the Macintosh. The DDK provides the same release of USB
  55. component software that ships on the introductory release of the
  56. Power Macintosh iMac system.
  57.  
  58.  
  59. Keeping up to date on Mac OS USB
  60. --------------------------------
  61.  
  62. To stay abreast with developments on Mac OS USB, check out the 
  63. Mac OS USB Developer web site for the latest information. As updates
  64. to Mac OS USB occur, development releases of the software will be
  65. made available from this web site. The URL for the web site is:
  66.  
  67. <http://developer.apple.com/dev/usb>
  68.  
  69. You can also subscribe to the Mac OS USB Developer
  70. mailing list where development questions regarding Mac OS USB
  71. are posed and answered. To submit a question to the mailing list
  72. you must first be a subscriber. To subscribe to the mailing list,
  73. send an email with the subject field set to "subscribe" 
  74. (omit the double quotes for the message) to 
  75.  
  76. usb@isg.apple.com
  77.  
  78. USB Alerts to developers are always posted to the mailing list.
  79. These alerts are also posted to the Mac OS USB Developer Web
  80. site at the following location.
  81.  
  82. http://developer.apple.com/dev/usb/devalerts.html
  83.  
  84.  
  85. Getting started with Mac OS USB
  86. -------------------------------
  87.  
  88. To develop with Mac OS USB v1.1, you will need either an iMac or a Power
  89. Macintosh system with a USB PCI card installed.  For the iMac, you must
  90. have either System Software 8.5 present, or have installed at least the 
  91. iMac Update v1.0.
  92.  
  93. USB v1.1 will support PCI USB cards from several vendors, however the 
  94. Keyspan card has been extensively tested for compatibility with MacOS 
  95. 8.0, 8.1 & 8.5 and an the complete range of PCI-based Macintosh models.   
  96. This card includes USB v1.1 software on diskette, and Keyspan is prepared 
  97. to technical support to customers.
  98.  
  99.   http://www.keyspan.com/products/USB/
  100.  
  101. The enclosed software is for developmental purposes and will support USB 
  102. PCI cards from other vendors, but it is not directly supported by Apple, 
  103. nor is it intended for end-users. End-user customers are encouraged to 
  104. purchase a PCI USB card that includes licensed software and support.
  105.  
  106. You may find that development on a Power Mac system with a USB PCI card 
  107. and serial port, is easier, as you can use the Power Mac Debugger with a 
  108. second Power Macintosh system. A Power Macintosh system with ADB
  109. keyboard is useful for debugging with Macsbug, since there are cases when
  110. the system cannot process keystrokes from a USB keyboard.
  111.  
  112.  
  113. Installing the Mac OS USB Software
  114. ---------------------------------
  115.  
  116. Before using the enclosed software on an iMac, you must already have installed
  117. the iMac Update 1.0.
  118.  
  119. To install the USB System Software components, 
  120. 1. remove all files with the following names from your Extensions Folder, 
  121.  
  122.      USB Support,
  123.   USBCompositeDriver,
  124.   USBFamilyExpert,
  125.   USBHIDKeyboardModule,
  126.   USBHIDMouseModule,
  127.   USBHIDUniversalModule,
  128.   USBHubDriver0,
  129.   USBHubDriver1, and
  130.   USBOpenHCIDriver
  131.  
  132. 2. drag copy the contents of the folder
  133.  
  134. :USBDDK:Extensions-AppleBuilt: 
  135.  
  136. to the Extensions folder.
  137.  
  138. 3. Before you reboot, modify the file "USB Support" to include
  139. a new resource 'usbx' (1984).  Without this resource, this release of
  140. USB will not load. The following alert is raised to indicate that the 
  141. resource is not present.
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157. Important Notes on Installation and Use of this DDK software
  158. ------------------------------------------------------------
  159.  
  160. This DDK will let you look at the sources to some working class 
  161. drivers, build the examples, and develop & build your own code.
  162.  
  163. Please remember that these driver samples are Copyright Apple 
  164. Computer, Inc.. You may use the supplied code to develop Class 
  165. Drivers for your devices. As for publishing the source code, please
  166. check first with the Mac OS USB DDK License agreement, included
  167. in this DDK.
  168.  
  169. The current driver samples may, reflect the latest
  170. state of the art of driver writing for USB in the Mac OS. Note that
  171. the PrinterClassModule sample is for example
  172. purpose only. This sample is the basis for real
  173. drivers under development, however we are unable to provide
  174. the actual class driver code. The remaining examples are the
  175. real code for the Keyboard HID, Mouse HID, Universal HID, and 
  176. Composite class drivers which will ship on the iMac
  177.  
  178. While not extensively tested (by the development team), 
  179. the sample sources have been tweaked slightly to make builds 
  180. under CodeWarrior some what less problematic. The project files 
  181. are provided to help jumpstart your development process.
  182.  
  183.  
  184. Using the Mac OS USB DDK under MPW
  185. ----------------------------------
  186.  
  187. For previous releases of the USB DDK, we provided a current 
  188. UserStartup•USBDDK and makefiles for each of the sample class
  189. drivers. As there are very few developers who program
  190. with the MPW environment and to expidite the release of this 
  191. DDK, we will no provide make files for the class driver samples, 
  192. nor UserStartup files for MPW.
  193.  
  194. If MPW is your primary development platform and you need 
  195. a make file for one of the example class drivers, submit a 
  196. request to the Mac OS USB mailing list and a sample make file, if
  197. available for the example, will be sent to you. See the section
  198. "Keeping up to date on Mac OS USB" above for information on
  199. how to subscribe to the Mac OS USB Developer mailing list.
  200.  
  201.  
  202. Using the Mac OS USB DDK with MetroWerks CodeWarrior
  203. ---------------------------------------------------
  204.  
  205. We have supplied MetroWerks CodeWarrior project files for
  206. all of the USB Modules code examples. All of the project
  207. files were created using CodeWarrior Pro 1, IDE 2.0. The 
  208. project files are also compatible with CodeWarrior Pro IDE 
  209. 2.1, 3.0 and later.
  210.  
  211. For the CodeWarrior IDE environments v2.0 - v3.0, you must use
  212. the Universal Interface & Libraries v3.1. The examples will
  213. not build using the interfaces supplied with the CodeWarrior
  214. v.2 - v3.0 environments. The URL for the Developer Development
  215. Kits web page is
  216.    
  217.    <http://developer.apple.com/sdk/>
  218.  
  219. As mentioned for MPW, it is highly recommend that you use 
  220. one Macintosh for coding purposes and one Mac (aka "Target"
  221. system) for checkout/testing purposes.
  222.  
  223. The supplied project files will place the built drivers
  224. and extensions into the Target folder of the DDK.
  225.  
  226.  
  227. Installing the Mac OS USB DDK for CodeWArrior for the First Time
  228. -----------------------------------------------------------
  229.  
  230. 1. You can place the USBDDK anywhere on your development
  231.    system for the CodeWarrior environment. The access paths
  232.    for the project files are project and compiler relative.
  233.    If you move the examples folders out of the DDK, you must
  234.    fix the access paths so that the sources can be found.
  235.   
  236. 2. Ensure that the CodeWarrior IDE environment has the 
  237.    Universal Interfaces and Libraries 3.1 installed. The
  238.    download file from the DDK website includes instructions
  239.    for upgrading your CodeWarrior environment. Note that if
  240.    you upgrade your interfaces, you will also need to 
  241.    upgrade your precompiled headers. The supplied CodeWarrior
  242.    project files do not use precompiled headers.
  243.  
  244. 3. Copy the USB.h file included in this SDK to the 
  245.    ":Mac OS Support:Headers:Universal Headers:" folder.
  246.  
  247. 4. You will need to create a folder by the name
  248.  
  249.     "USBDDK:Extensions-MCWBuilt"
  250.  
  251.    This is the folder where the CodeWarrior projects will place 
  252.    the built examples. If this folder does not exist, or the folder 
  253.    name is named differently, the class driver samples will be
  254.    created in the CodeWarrior folder.
  255.  
  256. Updating a Previously Installed Mac OS USB DDK for CodeWarrior
  257. -------------------------------------------------------------
  258.  
  259. 0. Note the change of name for the DDK from NeptuneDDK to
  260.    USBDDK.
  261.  
  262. 1. Copy the USB.h file included in this SDK to the 
  263.    ":Mac OS Support:Headers:Universal Headers:" folder. Do not
  264.    use the USB.h header file from an earlier USB DDK with the
  265.    supplied project files, as the examples may not build.
  266.  
  267. 2. If you experience compiler errors with the program samples,
  268.    check whether you have updated the USB.h header in the
  269.    ":Mac OS Support:Headers:Universal Headers:" folder.
  270.  
  271. 3. You will need to create a folder by the name
  272.  
  273.     "USBDDK:Extensions-MCWBuilt"
  274.  
  275.    This is the folder where the CodeWarrior projects will place 
  276.    the built examples. If this folder does not exist, or the folder 
  277.    name is named differently, the class driver samples will be
  278.    created in the CodeWarrior folder.
  279.  
  280. Using the CodeWarrior Project Files
  281. ---------------------------------
  282.  
  283.    For the following samples, there is only a single target for 
  284.    each project:
  285.  
  286.    CompositeClassDriver
  287.    KeyboardModule
  288.    MouseModule
  289.    UniversalModule
  290.  
  291.    For the PrinterClassDriver example, compile the targets in 
  292.    the following order
  293.  
  294.   1. PrinterClassDRVR - creates the 68K DRVR resource
  295.   2. PrintClassDriver - creates the USB PrintClassDriver module
  296.   3. ChooserPack.rsrc - creates the "PACK" resource
  297.   4. USB Chooser Driver - creates the Chooser extension for the 
  298.      USB printer
  299.  
  300. Installing the Mac OS USB Components onto your Target System
  301. -----------------------------------------------------------
  302.  
  303. IMPORTANT NOTE: Do not install the USB Extensions and Libraries
  304. into the System Folder of a CPU that has the USB Support integrated
  305. into the System ROM.
  306.  
  307. 1. Delete any existing files prefixed with "USB" from your system
  308.    folder's extension folder.  This applies only if an earlier 
  309.    pre-release version of Mac OS USB DDK software had been 
  310.    installed.
  311.  
  312. 2. Drag all the files from the 'USBDDK:Extensions-AppleBuilt' 
  313.    folder to the System Folder (ultimately destined for the 
  314.    system folder's extension folder). 
  315.  
  316. 3. Verify that all of the files that you dragged from the 
  317.    'Extensions-AppleBuilt' folder were placed in the system 
  318.    folder's extensions folder.
  319.    
  320.    
  321. Description of Installed Files
  322. --------------------------
  323. Files in the 'Extensions-AppleBuilt' folder:
  324. Files:                  Description:
  325. USBCompositeDriver      A class driver which is loaded for class 0 &
  326.                         and subclass 0 devices (typically keyboards &
  327.                         mice, although a few printers & modems appear 
  328.                         as composite class devices).
  329.                             
  330. USB Support             The INIT (actually an 'expt') portion of the Family 
  331.                         Expert. Loaded prior to the INIT parade, it starts 
  332.                         the 'find a USB bus (i.e. UIM driver), loads the
  333.                         hub driver (for the root hub), and starts
  334.                         the hub driver running.  Once running, the
  335.                         hub driver locates devices attached to the
  336.                         port and asks the FamilyExpertLib to load
  337.                         drivers for the devices connected to the
  338.                         hub's ports.
  339.  
  340. USBHubDriver0 &         The Hub driver for the root hub, the Apple USB 
  341. USBHubDriver1           keyboard's hub, and some 3rd party hubs.
  342.  
  343. USBKeyboardModule       The HID Module loaded for a keyboard
  344.                         interface (typically in a compound device)
  345.                             
  346. USBMouseModule          A HID Module loaded for a mouse interface
  347.                         (typically in a compound device).
  348.                             
  349. USBHIDUniversalModule   A HID Module designed to support a number of 3rd
  350.                         party gaming devices via Game Sprockets.
  351.                         Refer to the "Mac OS USB Compatibility Notes"
  352.                         for a description of the game devices supported.
  353.                             
  354. USBOpenHCIDriver        The HAL (Hardware Abstraction Layer), also
  355.                         known as the "UIM" (USB Interface Module).
  356.                         This driver provides an abstracted interface
  357.                         to the OpenHCI host controllers on Mac
  358.                         motherboards and PCI controller cards.
  359.                             
  360. USBPrintDriver          A Printing Class Driver for experimentation
  361.                         purposes.  Printing WILL NOT be functional
  362.                         simply with the addition of this file.  The
  363.                         chooser extension needed for USB printing
  364.                         is still in development and has not yet
  365.                         been released.
  366.     
  367. Known Issues
  368. ------------
  369.  
  370. The following is a list of known issues with this final release
  371. of the USB DDK.
  372.  
  373.   - If you install this release of USB 1.1f3 directly without adding
  374.     the 'usbx' (1984) resource, then USB will not load. This is
  375.     by design.
  376.  
  377.   - The USBSampleStorageDriver does not correctly demonstrate how to
  378.     handle a hot unplug situation. This sample will be updated to 
  379.     demonstrate how this situation should be properly handled. The 
  380.     existing sample sets up a Timer Task which when fired makes a
  381.     call to SystemTask.  The call to SystemTask is not supported
  382.     from an interrupt context.
  383.  
  384.      - Mac OS USB only provides support for a single control pipes per
  385.     device. We are investigating support for multiple control pipes
  386.     per device as per USB Spec 1.1, in a future release of Mac OS USB.
  387.  
  388. Contact Information
  389. -------------------
  390.  
  391.   Mac OS USB DDK Upgrades and latest information:
  392.     
  393.     Check the Developer Development Kits web page for
  394.         upgrades to the Mac OS USB DDK. The web page is
  395.         
  396.         <http://developer.apple.com/sdk/>
  397.  
  398.     For the latest information on Mac OS USB, check the Mac OS USB web page.
  399.     The web page is
  400.  
  401.     <http://usb.apple.com>
  402.  
  403.   For Bug Reports:
  404.  
  405.     To ensure the appropriate data is collected, please use the Bug Reporter  
  406.     to send us your bug reports. The Bug Reporter can be found at: 
  407.  
  408.     <http://developer.apple.com/bugreporter>
  409.  
  410.     When reporting problems, please include the machine configuration, 
  411.     including the vendor of the PCI USB card which you have tested with.
  412.  
  413.   For Technical Questions:
  414.  
  415.                 For generic Mac OS USB questions, submit them to the Mac OS USB 
  416.     Developer mailing list. Refer to the section above "Keeping up to date 
  417.     on Mac OS USB" for information on how to subscribe to this mailing list.
  418.     Often questions can be answered by someone on the mailing list.
  419.  
  420.  
  421.                 If your question is not answered on the mailing list, or if your question 
  422.     is proprietary, contact Worldwide Developer with purchased development-level 
  423.     technical support incidents at
  424.  
  425.     dts@apple.com
  426.  
  427.     Technical support incidents are bundled in our Premier and Select 
  428.     Developer programs. For information about joining our programs, 
  429.     please visit our Apple Developer Connection web site at 
  430.  
  431.     http://developer.apple.com/programs. 
  432.  
  433.     If you have never purchased a technical support incident and would like 
  434.     to find out how to do so, please visit the following site: 
  435.  
  436.     http://developer.apple.com/programs/techsupport.html . 
  437.  
  438.     
  439.   Comments, Suggestions and Enhancement Requests
  440.  
  441.     Please send all comments and suggestions regarding the Mac OS USB DDK to
  442.     
  443.     usb@apple.com
  444.  
  445.     All email sent to this address will be read, however, we will not be to
  446.     respond to all of your comments and suggestions.
  447.  
  448.         
  449.